개요

최근 토스에서 글을 쓰는 가이드 사이트를 찾게 됐다.^[1]
안 그래도 글을 어떻게 써야 하나, 정리를 어떻게 해야 하나 고민을 하고 있었는데 조금 생각 포인트들을 구체화하는데 도움을 주는 것 같다.

최근 고민

내 기술 정리의 문서는 결국 크게 개념과 실전으로 나뉜다.
개념, 문서 정리에 대한 내용은 무조건 knowledge 쪽에 담고, 직접 무언가를 해보는 행위가 들어간다면 무조건 topic에 넣는 식이다.

TOPIC 디렉토리 문제

내 글이 가지는 문제점 중 하나가 개념 정리글은 너무 추상적인 형태로 머무른다는 것이다.
기술의 원리와 작동 방식을 설명하는데 있어 실습이 꼭 필요한 것은 아니지만, 실제로 보이는 자료와 예시가 함께 할 때 더 잘 기억되지 않나 싶다.

두번째로, TOPIC 쪽은 정말 너무 정리가 안 돼있다.
애초에 정리가 애매한 문서들을 박아넣으려고 만든 공간이긴 하지만, 막상 그렇게 되니 내가 직접 찾는 것도 쉽지 않는 상황이 되어가고 있다.
여기에 어떻게 정리할지 애매하다는 그런 압박감이 오히려 토픽을 늘리는 것을 꺼려지게 만든다.

혹시 내가 실습을 하는 방식에 문제가 있는 것은 아닐까?
실습을 할 때, 하나의 목적을 가지고 시작하긴 하지만 하다보면 계속 다른 부분까지 깊게 파고드는 구석이 있다.
트러블 슈팅으로 시작했는데 막상 보니 기술 원리를 파고 있다던가..
실습으로 시작했는데 중간에 막혀서 트러블 슈팅을 하고 있다던가..
목표를 명확하게 한 뒤에 시작한다고는 하지만, 이 목표가 정말 내 글을 전부 담을 수 있도록 내가 진행하지는 않는 것 같다는 게 하나의 문제라는 것이다.
이것이 문제라면, 이 문제의 원인은 두 가지 정도로 생각할 수 있다.

• 처음 주제를 규정짓는 바운더리나 층위에 문제가 있다.
  • 현재는 트러블 슈팅, 실험, 세팅 정도로 분류를 나눈다.
  • 그런데 실험,세팅을 하다가 트러블 슈팅을 하기도 한다.
  • 처음 목적에 따라 글을 분류하나, 파생되는 다양한 태스크들이 그 자체로 하나의 분류 항목을 가져도 될 만큼 분류 기준이 나이브한 것 같다.
• 내가 너무 삼천포로 빠진다.
  • 근데 이건 당연하다고 생각한다.
  • 어떤 문제를 해결하는데 어떻게 지식 공부가 안 들어가며, 애초에 한번에 해결할 문제면 문제도 아니었을 것이다.
  • 문제의 원인을 탐구하는 과정 상 어떠한 종류의 탐구가 일어나도 그것은 절대 이상한 것이 아니라는 게 내 생각이다.

KNOWLEDGE 디렉토리 문제

현재 KNOWLEDGE 디렉토리 구조에 대해선 사실 굉장히 만족 중이다.
그러나 조금 방식의 변화를 가져야겠다고 생각했던 시점은 Istio 1기 - Istio Hands-on 스터디를 진행할 때.
이스티오라는 툴을 정리할 때 가급적 하나의 문서로 정리하고 싶었지만 막상 해보니 내용이 너무 방대해서 그렇게 하는 것이 오히려 비효율적이라는 판단이 섰다.

그래서 쿠버네티스 마냥 하위 디렉토리를 두는 것을 꺼리지 않는 것으로 간단하게 전략을 수정했다.

그럼에도 아직 고민 지점은 이 부분이다.
각 기술끼리 연관되는 지식은 어떻게 위치시켜야 하는가?
아르고 롤아웃과 이스티오 연계는 현재 아르고 롤아웃 하위에 위치한다.

이 부분은 내가 처음 문서를 정리할 때부터 있었던 고질적인 이슈와도 연관이 된다.
가령 IaaS, PaaS 같은 것들을 각각의 문서로 정리한다면 이걸 비교하는 문서는 어디에 있어야 하는가?
나는 이때 이 정도 개념들의 정리는 어차피 한 문서로 끝내버릴 수 있다고 결론지었다.

그런데 위 사례처럼 아르고 롤아웃, 이스티오는 한 문서로 엮을 만한 사이즈를 가지고 있지 않다.
위 문서는 다음의 두 가지 고민 지점을 내게 안겨준다.

• 문서의 위치 - 롤아웃 아래 있어야 하나? 이스티오 아래 있어야 하나?
  • 원래는 이런 문제를 전부 짬때리기 위해 TOPIC 디렉토리를 둔 것이긴 하다.
• 실습이 없다고 해도 TOPIC에 있는 게 맞지 않을까?
  • 위 문서는 나중에 실제 실습도 곁들였으니 TOPIC으로 넘어갈 수는 있다.
  • 그러나 위 문서는 실습을 했다고 하나, 사실 롤아웃에서 다른 툴을 연계하는 설정 지식을 담고 있어 롤아웃 자체를 이해하는데 도움을 준다.
  • 하지만 실습이 들어가지 않으면서 명확하게 위치를 잡기 애매한 문서들은 앞으로도 많아질 것이다.

애매한 목적의 글

기본 디렉토리를 나누는 기준은 단순 지식이냐, 행동이 들어가는가이다.
그런데 사실 이렇게 분류하기에 너무 애매한 목적을 가지는 노트들이 있다.
어떻게든 한쪽 디렉토리로 넣으려고 하면 목적이 흐려지는 글들이다.

• 어떤 기술을 어떻게 운영하는 게 좋은지, 모범이나 패턴 노하우를 담는 글.
  • 단순하게 지식 노트 내부에 포함하면 길어지거나 주제를 벗어날 수 있음
  • 행동이랍시고 담기에는 지식의 내용을 담을 수 있음
    • 추가적으로 그냥 토픽에 넣으면 참고용 글 느낌이 되지만, 실제로는 해당 지식을 익히는데 동반되는 필수급 노트
• 아키텍처 설계
  • 지식이 많이 사용되나, 그 자체로 지식이라 하기엔?
  • 그러면 그냥 일반 토픽이랑 같나? 것도 아닌 듯.
• 코드 구현
  • 개발자가 전업은 아니어도 결국 코드를 만지게 되고, 분석을 한다.
  • 근데 코드를 쓰는 작업도 노트로 정리하는 게 맞는지도 조금 고민이 필요하다.
  • 하지만 코드 전체 구조를 설계하는 작업은 충분히 정리할 만하다.

문제 분석

노트 분류 목적

왜 처음에 이렇게 글을 나누었는지도 다시금 고민해본다.
기본적으로는 내 지식 체계를 정리하고 싶었다.
그리고 이를 토대로 나중에 언제라도 편하게 다시 글을 읽을 수 있게 하는 것이 주목표이다.
갑자기 쿠버 어떤 리소스를 작성하는 법이 기억이 나지 않는다던가, 프롬쿼리 작성법을 알고 싶다던가.
이걸 정리하는 글에 실습하며 담은 내용이 들어가면 너무 장황해지면 다시 글을 흡수하는데 문제가 생긴다.
그래서 실습과 지식을 나누게 됐다.

원인 정의

그런데 점점 글을 쓰다보니 실습 내용 자체가 중요한 것 같은 지식도 있고, 단일 지식이라 하기엔 애매한 글도 있더라는 것.
이런 중요하다 할 만한 글들이 전부 토픽에 때려박히면 나중에 꺼내기가 어렵다.

그렇다고 실습 내용을 지식 디렉에 넣는 것은 역시 문제가 있다.
토픽 중 지식과 긴밀한 결합을 하는 글을 식별하는 것이 핵심 관건인 것이다.

여기에 애매한 토픽들 간 분류가 이뤄지면 가시성이 향상조금 더 필요해보인다.
문제가 생기는 노트는 무엇인가?

• 토픽
  • 지식을 보조하는 수준 이상의 내용을 담는 노트.
    • 아직까지, 이런 글은 지식보단 토픽으로 넣는 게 현재 결론.
  • 순수 생각이나 고찰이 담기지만 이후에도 활용성이 높은 노트.
    • 디자인, 설계 내용 등 계획성이 들어갈 때 특히 그렇다.
  • 그냥 존나 긴 노트
    • 아무 내용 다 때려박힌 노트.. 트러블 슈팅도 했다가 내용 정리도 했다가..
• 지식
  • 두 지식이 결합된 형태의 노트.

원하는 목표

지식과 토픽은 역시 디렉토리로 명확하게 분류되는 편이 좋다.
지식쪽 노트를 보는데 필요한 토픽이 가시적으로 보이면 좋겠다.
디자인 관련 글이 명확하게 정리되면 좋겠다.
백링크를 달 때 이 글이 무엇이다, 명확해서 빠르게 캐치할 수 있으면 좋겠다.

해결해야 할 예시

• 클러스터 설치할 때 쿠버네티스와 카인드
• 이스티오와 프로메테우스 연동
• 게이트웨이 리소스 간 연동
• aas들 비교
• 디비 간 비교
• 클린 코드, 레이어드, 클린 아키텍처, 헥사 비교. - 언어 간 예시?
• 한 세팅에 긴 단계가 있을 때

브레인스토밍

지식과의 관계를 토대로 보는 토픽 분류

• 비교, 연계 등 두 가지 이상이 혼합
• 세팅이나 단계가 있는 프로세스
• 한 가지를 세부 분석

토픽으로 쓸 만한 패턴

• 사용법 - 모범 사례
• 분석 - 아키텍처, 지표나 로그, 동작 추적
• 세팅 - 설치나 연동
• 테스트 - 실험, 세팅 테스트
• 설계 - 아키텍처, 코드
• 구현 - 설계의 실현
• 트러블 슈팅 - 디버깅

지식은 원자적으로 두기?
상위 글로 비교를 묶는다?

한 문서의 참고

• 자식, 남매, 연관, 기타 문서

토픽 레벨 두기? - 결국 분류 아니냐 그리고 지식과의 관계는/
토픽 앞에 이니셜 붙이기?

• explain - 지식의 실현, 구현
  • 사용법 - 모범 사례
  • 분석 - 아키텍처, 지표나 로그, 동작 추적
  • 세팅 - 설치나 연동
• shooting - 문제 정의, 해결 과정과 결과
  • 트러블 슈팅 - 디버깅
• temp - 연습, 처음할 때
  • 테스트 - 실험, 세팅 테스트
• idea - 설계나 생각 기반, 그로부터 파생되는 구현 설명
  • 설계 - 아키텍처, 코드
  • 구현 - 설계의 실현

이들을 정렬 편의성을 위해 enum으로 치환.
하나의 파일 속성으로 두고 정렬 수단으로 활용.
디렉토리도 분류.

글 쓰는 프로세스.

• 토픽에 글을 쓴다.
• 다 쓰고 난 이후에 디렉터리화
  • 쉽게 태그 유지하기 위해
• 분할, 분류 작업.
• 각 글 앞에 접두사 붙이기
• 애매하게 잘 안 나눠지면 웬만하면 practice로 갈 듯.

그냥 세팅 테스트이고 실험이어도 중요한 내용일 수 있다.

개선 방안

그렇다면 어떻게 바꾸는 것이 더 효과적일까?
아울러, 토픽을 어떻게 활용하는 것이 내 지식 정리에 더 도움이 될까?

토스의 문서 유형 정리 방식이 여기에 도움을 줄 수 있을 것 같다는 생각이 들었다.
사실 이걸 읽다가 현재 글들의 문제를 인식하게 됐는데, 고찰을 해보면서 개인적으로는 다른 방식으로 개선할 계획을 세우게 됐다.
이 유형은 독자의 관점을 중시한 방식이라고도 할 수 있다.
하지만 나는 글을 정리하는 입장이고 미래의 나 역시 독자이기는 하게지만 그럼에도 단순한 독자와는 거리가 멀다.

TOPIC 디렉토리 구조

처음 구상한 개선 방안은 디렉토리를 쪼개는 것이다.

• BUFFER
  • 처음 토픽을 만들 때 활용하는 디렉토리
  • 아무리 목적을 명확히 하고 시작하더라도, 다양한 이유로 문서는 분할될 수 있다.
  • 이때 그런 분할된 문서들을 한번에 보기 좋게 두는 버퍼 디렉토리이다.
  • 즉 이 디렉토리는 한번 맺음이 난다면 내용물을 플러시해야 한다.
  • 실제로는 배치하지 않고 그냥 TOPIC 디렉토리 자체를 이렇게 활용할 수도 있다.
• PROOF
  • KNOWLEDGE의 지식이 지식으로만 남지 않도록 하기 위한 디렉토리이다.
  • 지식을 예시와 실습을 통해 실제로 적용한 내용을 담는다.
  • 이 부분은 최대한 간결하게 주제와 맞는 내용만 전달한다.
  • 가령 리소스 사용법이 주제라면, 세팅법에 대해서 담지 않는다.
• TASKS
  • 여기가 새로운 짬통으로, 딱히 분류되지 않는 것들을 때려박는다.
  • 궁금한 내용에 대해 진행한 실험을 담는다.
  • 특정 지식이나 기술에 얽매이지 않은 형태로 광범위한 플로우를 가진 실습을 담는다.
  • 명확하게 하나의 목적을 담은 거대한 글이 있다면, 여기에서도 하위 디렉토리를 나눌 수 있을 것 같다.
• TROUBLE-SHOOTING
  • 중간 중간 마주치는 이슈거리들을 정리한다.
    • 규모가 다양할 수 있다.
  • 글 형식은 최대한 잡아 둔다.
    • 문제 정의 - 현재 기준으로 간단하게 정리
    • 계획 - 어떤 것을 시도할지 방향만 정리
    • 진행 - 실제 진행 내용 정리. 진행하면서 새롭게 추가된 방향, 계획을 위로 올릴 수도 있다.
      • 대신 헤딩으로 구분만 잘하자
    • 결론 - 알게 된 것, 생각한 지점 정리.
      • 모든 트러블 슈팅이 의미 있는 것은 아닐 수 있다.
      • 교훈이 아니어도 좋고, 주관적 의견을 남긴다.

기존과 마찬가지로, 특정 기술을 기준으로 두거나 도메인을 바탕으로 분류하지는 않는다.
내용 상의 분류는 태깅만으로 최대한 해결하는 기조를 유지한다.
어차피 관련 있는 내용이라면 백링크를 달게 되며, 지식 문서에서는 참조된 문서를 조회하여 토픽 디렉토리에 접근할 수도 있다.

실용적으로 고려하기

topic을 여러 개로 분할하는 아이디어는 좋다.
디렉토리를 나누는 것도 나쁘지는 않다.
그런데 이게 명확하게 나눠질 수 있게 글을 쓰는 것이 먼저 중요한 것 같다.

예를 들어보자.
이스티오의 운영 모범 사례를 정리해보자.

• 모든 이스티오의 태그는 #cncf/istio 로 시작한다.
• 하위로 무얼 달던, 저 태그가 있으면 이스티오에서 확인이 가능하다.
• 어떤 설정이 어디에 도움이 되는지 분류한다.
• 최적화, 보안, 기본 설정, 모니터링 툴 연계.

토픽을 쓰는 방식

• knowledge의 보완.
  • 어떤 기술 사용법
  • 모범 사례
  • 툴 간의 연계
• 실습
  • 잘 모르는 기술을 익히는 맥락에서 초안 정리
  • 궁금한 것을 테스트
• 트러블 슈팅
• 아키텍처나 코드의 설계, 디자인

토픽 중에는 knowledge에서 참고하는 것이 강력하게 권장되거나 긴밀하게 결합되는 노트가 있다.
반면 그냥 단순하게 테스트하거나 정리하는 용도 존재한다.
어떤 지식에는 핵심인데 다른 지식에는 핵심이 아닌 토픽도 있다.
두 곳에 전부 핵심인 토픽도 있나?

• 베이시스
• 디자인
• 프랙티스
• 트러블슈팅

KNOWLEDGE 디렉토리 구조

이 디렉토리는 크게 달라지게 하고 싶지는 않다.
앞으로 추가될 문서가 문제지 현재까지는 아주 괜찮은 상태를 유지하고 있다고 생각한다.
처음에는 그냥 문서 정리하면서 분류가 애매해진 문서들은 TOPIC.TASKS로 뺄까도 생각해봤다.

그러나, 그러면 내가 그리도 극혐하는 쿠버네티스 문서와 다를 게 없어진다.

개념 정리에 들어가야 할 것 같은 수많은 내용이 Reference에 쳐박혀 있어 처음에 고통을 많이 받았다..
막상 보면 거의 실습에 가까운 정리가 돼있어 Tasks에 들어갈 것 같은 것들도 Reference에 들어가있는 등, 매번 보면서 느끼지만 분류가 불분명하다고 생각한다.

아무튼 현재 내린 결론은 개념적 지식을 전달하기 위한 문서는 역시 KNOWLEDGE에 위치하는 게 맞다는 것.
대신 예시와 실습을 곁들여야 효과적인 문서들이 무조건 있기 때문에, 이들은 TOPIC.PROOF 디렉토리를 활용하는 방향으로 생각을 잡았다.
이때 중요한 것은 지식 문서가 토픽 문서에 의존하지 않는다는 것이다.
지식 문서와 토픽 문서의 의미적 구분이 명확하기에 최소한 이 둘 간의 위계에는 예외가 없는 편이 좋다.

데이터뷰 개선

그렇다면 또 고민할 지점이 데이터뷰이다.

최근 들어 도입한 데이터뷰 조회 방식은 위와 같이 하위 문서와 관련 문서의 구분이다.
디렉토리가 구분돼있을 때 매우 효과적인 방식이라고 개인적으로 생각하고 있다.
여기에서 개선을 한다면 관련 문서를 다시 한번 세분화하거나, 정렬 기준만 바꾸는 것이다.

지식 문서는 토픽에 의존성을 가지지 않으면서도 효과적으로 연관되는 토픽을 제대로 보여주기 위한 방법이 필요하다.
topic.proof에 들어가는 문서의 경우 특히 그렇다.

• KNOWLEDGE 측
  • 같은 knowledge간의 연관, topic.proof 와의 연관이 중요하다.

관련 문서

참고